(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI PathBuildRoot Function
Forms the Windows/DOS, root path string for the specified logical drive number. .
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function PathBuildRoot(szRoot : LPSTR; iDrive : Integer) : LPSTR;
Parameters
szRoot [in/out] A pointer to the buffer into which the NULL-terminated, ANSI or Unicode output string should be written. As a minimum this buffer should have a size of four (4) ANSI or Unicode characters, depending on if the ANSI (PathBuildRoot and PathBuildRootA) or Unicode (PathBuildRootW) version of the function is called.
iDrive [in] An integer value greate or equal to zero (0) and smaller than or equal to 25, that represents the Windows/DOS logical drive number.
Return Values
Always returns a pointer to the beginning of the buffer passed to the function on call (at least under Vista with SP1 and IE 8), but see Remarks, below.
Remarks
If the function succeeds the returned pointer points to the beginning of the created path string. However, even if a path is not written to the buffer for any reason, for example because the buffer is too small, the function still returns a pointer to the beginning of the buffer.
If a null-pointer is specified as the address of the buffer on call, the function returns NIL.
If the function is successful in forming the root path, the resulting output to the buffer will overwrite any previous content and the root path string is terminated by a single or double byte null character, depending on which version of the function was called.
The drive letters returned in the buffer are always upper case characters.
The function apparently verifies neither the validity of the drive number, nor that of the path.
Example
PROCEDURE TForm4.TestShlWAPIPathBuildRoot(Sender : TObject); VAR rootpathbuf : ARRAY[0 .. 24] OF CHAR; VAR wcharpathbuf : ARRAY[0 .. 24] OF WideChar; VAR invalidbuf : ARRAY[0 .. 1] OF CHAR; VAR logdrvnum : INTEGER; VAR apiretstrp : LPSTR; VAR wcharstrp : LPWSTR; // = PWideChar VAR newinfoline : STRING; BEGIN FillChar(rootpathbuf, Length(rootpathbuf), #0); FillChar(wcharpathbuf, Length(wcharpathbuf), #0); logdrvnum := 0; apiretstrp := NIL; wcharstrp := NIL; newinfoline := ''; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(rootpathbuf)); Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(rootpathbuf, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); Inc(logdrvnum); apiretstrp := NIL; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(rootpathbuf)); Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(rootpathbuf, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); Inc(logdrvnum); apiretstrp := NIL; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(rootpathbuf)); Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(rootpathbuf, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); //Test function with a initialized path string Inc(logdrvnum); apiretstrp := NIL; FillChar(rootpathbuf, Length(rootpathbuf), #0); rootpathbuf := '\\Server1\share\'; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum) + ', a buffer initialized with ' + rootpathbuf; newinfoline := newinfoline + ', and a buffer size of ' + IntToStr(SizeOf(rootpathbuf)); Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(rootpathbuf, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) + ' and in the buffer: ' + rootpathbuf ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); wcharstrp := NIL; logdrvnum := 24; newinfoline := 'PathBuildRootW called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(wcharpathbuf)); Memo1.Lines.Add(newinfoline); wcharstrp := PathBuildRootW(wcharpathbuf, logdrvnum); IF (wcharstrp <> NIL) THEN newinfoline := 'Returned: ' + PWideChar(wcharstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); wcharstrp := NIL; Inc(logdrvnum); newinfoline := 'PathBuildRootW called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(wcharpathbuf)); Memo1.Lines.Add(newinfoline); wcharstrp := PathBuildRootW(wcharpathbuf, logdrvnum); IF (wcharstrp <> NIL) THEN newinfoline := 'Returned: ' + PWideChar(wcharstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); //Try forcing an error wcharstrp := NIL; Inc(logdrvnum); newinfoline := 'PathBuildRootW called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(wcharpathbuf)); Memo1.Lines.Add(newinfoline); wcharstrp := PathBuildRootW(wcharpathbuf, logdrvnum); IF (wcharstrp <> NIL) THEN newinfoline := 'Returned: ' + PWideChar(wcharstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); apiretstrp := NIL; logdrvnum := 1000; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a buffer size of ' + IntToStr(SizeOf(invalidbuf)) + ' // NOTE the too small buffer !!!'; Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(invalidbuf, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); apiretstrp := NIL; logdrvnum := 1000; newinfoline := 'PathBuildRoot called with ' + IntToStr(logdrvnum); newinfoline := newinfoline + ' and a NIL pointer as the address of the buffer'; Memo1.Lines.Add(newinfoline); apiretstrp := PathBuildRoot(NIL, logdrvnum); IF (apiretstrp <> NIL) THEN newinfoline := 'Returned: ' + PChar(apiretstrp) ELSE newinfoline := 'FAILED'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); Memo1.Lines.Add(''); END;
Under Windows Vista with Service Pack 1 (SP 1) and Internet Explorer 8 (IE 8), the above code produced the following results.
PathBuildRoot called with 0 and a buffer size of 25 Returned: A:\ PathBuildRoot called with 1 and a buffer size of 25 Returned: B:\ PathBuildRoot called with 2 and a buffer size of 25 Returned: C:\ PathBuildRoot called with 3, a buffer initialized with \\Server1\share\, and a buffer size of 25 Returned: D:\ and in the buffer: D:\ PathBuildRootW called with 24 and a buffer size of 50 Returned: Y:\ PathBuildRootW called with 25 and a buffer size of 50 Returned: Z:\ PathBuildRootW called with 26 and a buffer size of 50 Returned: PathBuildRoot called with 1000 and a buffer size of 2 // NOTE the too small buffer !!! Returned: PathBuildRoot called with 1000 and a NIL pointer as the address of the buffer FAILED
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (PathBuildRoot and PathBuildRootA) and Unicode (PathBuildRootW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.: 4.71
Min. ShlWAPI.dll version based on SST research: 4.71
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.: Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later
See Also
PathGetDriveNumber.
 
Windows APIs: PathBuildRoot PathGetDriveNumber


Document/Contents version 1.00
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com